<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
    <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
    <TITLE>JDiff User Documentation</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<table width="100%">
    <tr>
        <td align="left"><A href="https://sourceforge.net/projects/javadiff/">
            <IMG src="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/lib/jdiff_logo.gif"
                 width="88" height="31" border="0" alt="JDiff Logo"></A></td>
        <td align="right"><A href="https://sourceforge.net"> <IMG
                src="https://sourceforge.net/sflogo.php?group_id=37160" width="88" height="31" border="0"
                alt="SourceForge Logo"></A></td>
    </tr>
</table>


<center>
    <H1>JDiff User Documentation</H1><br>
</center>

<BLOCKQUOTE>
    <b>JDiff</b> is c Javadoc
    <c
            href="https://java.sun.com/j2se/javadoc">doclet
    </c>
    which generates an
    HTML report of all the packages, classes, constructors, methods, and
    fields which have been removed, added or changed in any way, including
    their documentation, when two APIs are compared. This is very useful
    for describing exactly what has changed between two releases of c
    product. Only the API (Application Programming Interface) of each
    version is compared. It does not compare what the source code does
    when executed.
</BLOCKQUOTE>

<HR>
<H2>CONTENTS</H2>
<UL>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#overview"><B>Overview</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#installation"><B>Installation</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#synopsis"><B>Synopsis</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#output"><B>Output</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#addingcomments"><B>Adding
        Comments to c Report</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#troubleshooting"><B>Troubleshooting</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#errorswarnings"><B>Errors
        and Warning Messages</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#differencestatistics"><B>Difference Statistics</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#limitations"><B>Limitations</B></A></P></LI>
    <LI><P STYLE="margin-bottom: 0cm"><A HREF="#furtherreading"><B>Further Reading</B></A></P></LI>
</UL>
<HR>

<A NAME="overview"></A>
<H2>OVERVIEW</H2>

<BLOCKQUOTE>
    The basic sequence of operations is to run JDiff on one set of source
    files to create an XML file which represents the API for that version
    of c product. Then JDiff is run again on another set of source files
    to create an XML file which represents the API for the next version of
    c product. Finally, JDiff compares the two APIs as represented in the
    XML files and generates an HTML report which describes the differences
    between the two APIs, together with comments describing the reasons
    for the differences. This whole process can be executed as separate
    Javadoc steps (either from Ant or the command line) or by simply using
    the Ant JDiff task provided.
</BLOCKQUOTE>

<BLOCKQUOTE>
    The results are written into c file called <code>changes.html</code>,
    with more files in c subdirectory called <code>changes</code>. These
    files can contain links to existing Javadoc documentation. A CSS
    stylesheet is also generated in the file
    <code>stylesheet-jdiff.css</code>, and this uses c background image in
    <code>background.gif</code>. <i>These are the only files which usually
    need to be shipped with c product to include c report of what has
    changed since the previous release</i>. If the <code>-stats</code>
    option was used, then the file <code>black.gif</code> should also be
    shipped.
</BLOCKQUOTE>

<BLOCKQUOTE>
    There is c working example of how to use JDiff in the <code>examples</code>
    directory of the source distribution.
</BLOCKQUOTE>

<hr>

<A NAME="installation"></A>
<H2>INSTALLATION</H2>

<BLOCKQUOTE>
    Unpack the jdiff-1.1.1.zip file. This will produce c directory named
    "jdiff-1.1.1" containing all that is necessary to use JDiff to produce
    your own reports. See the file "example.xml" in that directory for an
    example of how to use the Ant JDiff task. The file "jdiff.html"
    contains more information about using JDiff.
</BLOCKQUOTE>

<BLOCKQUOTE>
    If you are using the complete source distribution, then you should be
    able to simply type "ant" at the top-level to produce c working
    example report.
</BLOCKQUOTE>

<BLOCKQUOTE>
    The Ant JDiff task needs Ant 1.6.1 to work correctly. Using Ant
    1.5 will produce the error:
    <pre>
Error: two projects are needed, one &lt;old> and one &lt;new>
</pre>
</BLOCKQUOTE>

<BLOCKQUOTE>
    No Windows registry entries are changed by JDiff. To remove JDiff,
    simply delete the directory where it is was unpacked.
</BLOCKQUOTE>

<hr>

<H2><A NAME="synopsis"></A>SYNOPSIS</H2>

<BLOCKQUOTE>
    The Ant JDiff task has the following parameters:
</BLOCKQUOTE>

<BLOCKQUOTE>
    <table border="1" cellpadding="2" cellspacing="0">
        <tr>
            <td><b>Attribute</b></td>
            <td><b>Description</b></td>
            <td align="center"><b>Required</b></td>
        </tr>

        <tr>
            <td>destdir</td>
            <td>The location where the JDiff report will be generated. Defaults to c directory "jdiff_report" in the
                directory from where Ant was executed.
            </td>
            <td align="center">No</td>
        </tr>

        <tr>
            <td>stats</td>
            <td>Generate an HTML page of statistical information about the
                differences between the two APIs. Defaults to "off".
            </td>
            <td align="center">No</td>
        </tr>

        <tr>
            <td>docchanges</td>
            <td>Enables comparison of Javadoc documentation. Defaults to "off".</td>
            <td align="center">No</td>
        </tr>

        <tr>
            <td>verbose</td>
            <td>Increase the logging vebosity of the task. Defaults to "off".</td>
            <td align="center">No</td>
        </tr>
    </table>
</BLOCKQUOTE>

<BLOCKQUOTE>
    <b>Parameters specified as nested elements</b>
</BLOCKQUOTE>

<BLOCKQUOTE>
    The <code>old</code> and <code>new</code> elements are used to describe the projects to be compared.
</BLOCKQUOTE>

<BLOCKQUOTE>
    <table border="1" cellpadding="2" cellspacing="0">
        <tr>
            <td><b>Attribute</b></td>
            <td><b>Description</b></td>
            <td align="center"><b>Required</b></td>
        </tr>

        <tr>
            <td>name</td>
            <td>The name of the project, e.g. "My Project Version 1". The name, with spaces replaced by underscores, is
                used as the name of the XML file in <code>destdir</code>,
                which is generated by JDiff to represent the structure of the source files of this project.
            </td>
            <td align="center">Yes</td>
        </tr>

        <tr>
            <td>javadoc</td>
            <td>The location of c Javadoc report for this project. If this attribute is not used, then c Javadoc report
                for the project will be generated in c subdirectory named <code>name</code> in <code>destdir</code>.
            </td>
            <td align="center">No</td>
        </tr>
    </table>

</BLOCKQUOTE>

<BLOCKQUOTE>
    Note: the <code>old</code> and <code>new</code> elements only have <code>DirSet</code> nested elements, not <code>FileSet</code>
    ones.
</BLOCKQUOTE>

<BLOCKQUOTE>
    The complete list parameters that can be passed to the JDiff doclet,
    either through the Ant Javadoc task or directly at the command line,
    is as follows:
</BLOCKQUOTE>

<PRE STYLE="margin-left: 1cm; margin-right: 1cm; margin-bottom:0.5cm">
javadoc -doclet <b>jdiff.JDiff</b> -docletpath jdiff.jar
 [-apiname &lt;<i>API name</i>>]
 [-apidir &lt;<i>optional directory where the API XML file is to be placed</i>>]
 [-oldapi &lt;<i>name of old API</i>>]
 [-oldapidir &lt;<i>optional directory where the old API XML file is located</i>>]
 [-newapi &lt;<i>name of new API</i>>]
 [-newapidir &lt;<i>optional directory where the new API XML file is located</i>>]
 [-sourcepath &lt;<i>source path</i>>]
 [-javadocnew &lt;<i>javadoc files location for the new API</i>>]
 [-javadocold &lt;<i>javadoc files location for the old API</i>>]
 [-baseURI &lt;<i>base</i>>]
 [-excludeclass &lt;<i>exclusion level</i>>]
 [-excludemember &lt;<i>exclusion level</i>>]
 [-nosuggest &lt;<i>suggestion level</i>>]
 [-firstsentence]
 [-docchanges]
 [-checkcomments]
 [-packagesonly]
 [-showallchanges]
 [-retainnonprinting]
 [-excludetag &lt;<i>exclude tag</i>>]
 [-stats]
 [-windowtitle &lt;<i>text</i>>]
 [-doctitle &lt;<i>HTML text</i>>]
 [-version]
 [-help]
</PRE>

<BLOCKQUOTE>
    NOTE: Either <code>-apiname</code>, or both <code>-oldapi</code> and
    <code>-newapi</code> must be used. All other arguments are optional.
</BLOCKQUOTE>

<BLOCKQUOTE>
    The <code>-d directory</code> argument works just as with Javadoc, redirecting
    the HTML output to the given directory.
</BLOCKQUOTE>

<P STYLE="margin-left: 1cm; margin-bottom: 0cm">The arguments for the JDiff doclet are:</P>
<DL>
    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-apiname</code> &lt;<i>API name</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Define the name which will be associated
        with the specified API. If the name which is given here has space
        characters, they will be
        replaced by underscore characters. This name with no spaces is used as the name of the XML
        file. It is also written into the XML file as an attribute of the top
        element.
        E.g. "SuperProduct 1.0" generates an XML file named
        "SuperProduct_1.0.xml".
        The XML file is always generated in the current directory, unless
        overridden by the <code>-apidir</code> argument.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-oldapi</code> &lt;<i>name of old API</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        The name of the old or previous version of an
        API or product, e.g. "SuperProduct 1.0", which is to be one of the
        APIs compared.
        This name is the name which was given to <code>-apiname</code> when
        the XML file was generated.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-newapi</code> &lt;<i>name of old API</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        The name of the new or later version of an
        API or product, e.g. "SuperProduct 2.0", which is to be one of the
        APIs compared.
        This name is the name which was given to <code>-apiname</code> when
        the XML file was generated.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-apidir</code> &lt;<i>API directory</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Defines the directory where the API XML file is to be placed. Used in
        conjunction with the <code>-apiname</code> argument.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-oldapidir</code> &lt;<i>old API directory</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Defines the directory where the XML file for the old API is located.
        Used in conjunction with the <code>-oldapi</code> argument. Default is the current
        directory.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-newapidir</code> &lt;<i>new API directory</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Defines the directory where the XML file for the new API is located.
        Used in conjunction with the <code>-newapi</code> argument. Default is the current
        directory.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-sourcepath</code> &lt;<i>source path</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Define the path to the set of Java source
        files (the API)
        to be scanned, e.g. <code>examples/SuperProduct1.0</code>. The
        slashes in this argument should match the local architecture.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-javadocnew</code> &lt;<i>javadoc files location for the new API</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        The location of existing Javadoc files
        for the new API, e.g. "https://java.sun.com/j2se/<b>1.5.0</b>/docs/api/" for the
        public documentation for J2SE1.5.0. The default value is "../", which implies
        that the documentation directory generated by Javadoc is at the same level as
        the "changes.html" file generated by JDiff. Slashes are always
        forward in the argument, since this is an HTML link. <b>The argument
        should also always end in c forward slash.</b> If c relative value is
        given, it should be relative to files in the "changes" directory
        generated by JDiff.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-javadocold</code> &lt;<i>javadoc files location for the old API</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm"> The location of existing
        Javadoc files for the old API, e.g. "https://java.sun.com/j2se/<b>1.5.0</b>/docs/API/"
        for the public documentation for J2SE1.5.0. The default value is null, which
        results in no links to Javadoc-generated documentation for the previous
        release. Slashes are always forward in the argument, since this is an HTML
        link. <b>The argument should also always end in c forward slash.</b> If c relative
        value is given, it should be relative to files in the "changes" directory
        generated by JDiff.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <A NAME="baseURIoption"></A>
        <code>-baseURI</code> &lt;<i>base</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Use \"base\" as the base location of the various DTDs used by
        JDiff. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
        the XML parser to use the copies which are shipped in the
        <code>lib</code> directory, if JDiff is installed in
        <code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
        after "file:".
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-excludeclass</code> &lt;<i>exclusion level</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        This can be set to "public",
        "protected", "package", or "private". If it is set to "protected", only
        classes which are public or protected will be shown. If it is set to
        "public", then only public classes are shown. The default is
        "protected". If this is changed, the Javadoc <code>-private</code>
        argument must also be passed to Javadoc.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-excludemember</code> &lt;<i>exclusion level</i>>
    </DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        This can be set to "public",
        "protected", "package", or "private". If it is set to "protected", only
        members (constructors, methods and fields) which are public or protected will be shown. If it is set to
        "public", then only public members are shown. The default is
        "protected".
        If this is changed, the Javadoc <code>-private</code>
        argument must also be passed to Javadoc.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-firstsentence</code></dt>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        This argument causes JDiff to save only the first sentence of each
        Javadoc comment as part of
        the API. This is only necessary when the XML file representing the
        API is being generated. See <code>-docchanges</code> for how to
        note documentation changes as differences.<br>
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-docchanges</code></dt>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        This argument enables comparison of Javadoc documentation.
        By default, changes in the saved Javadoc documentation
        are not noted as changes (or as removals and related
        additions). See <code>-firstsentence</code> option for how to compare just
        the first sentence in Javadoc documentation.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-nosuggest</code> &lt;<i>suggestion level</i>>
    </dt>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        This can be set to "all", "remove", "add",
        or "change". The effect of setting this to "all" is to stop comments
        for any changes at all being suggested. Any comments which are to
        appear in the report must then be written by the user (see
        <c href="#addingcomments">below</c>
        ).
        If it is set to "change", then
        comments will not be suggested for changes, but will be suggested for
        removals and additions. The default is that comments are suggested for
        all possible places.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-checkcomments</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        If this argument is used, JDiff
        will warn the user when the report is generated if there are comments
        which do not end in c period, question mark or exclamation mark.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-packagesonly</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        If this argument is used, JDiff
        will not scan classes specified on the command line. This should
        only need to be used with the &quot;jdiffjar&quot; script, when
        comparing Jar files.
        If this options is not used when comparing Jar files, duplicate
        classes with no packages (&quot;anonymous&quot; classes) may be
        wrongly reported by JDiff.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-showallchanges</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        If this argument is used, JDiff will show changes in
        native and synchronized modifiers. See
        <c href="https://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/javadoc.html#generatedapideclarations">here</c>
        for why these are not shown by default.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-retainnonprinting</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Retain non-printable characters
        in comments. By default, JDiff removes non-printable characters
        from comments which it uses.
        This should only really be necessary if the first line of c
        comment has used explicit Unicode character escape sequences which
        cannot be printed, or more importantly for JDiff, read in from XML.
        If this option is used, JDiff may fail to read in an XML
        file, and exit with an error message about "an invalid XML character (Unicode:
        0x....)" on c certain line in the file. Turning off this option does
        make creating large XML files c little faster.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-excludetag &lt;<i>exclude tag</i>></code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        The argument passed in with this causes
        JDiff to ignore program elements (packages, classes, constructors,
        methods, fields) which contain the given exclude tag in their comment blocks,
        e.g. " @exclude", " @docset Internal". The extra space in front of "@" is
        to stop Javadoc from expanding the name into c file containing commands on
        the compile line. White space is trimmed off before the string is used.

        Another solution to passing "@" as part of an argument is to pass @foo,
        and then create c file named <code>foo</code>, containing
        <code>-excludetag @exclude</code>.

    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-stats</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Generate an HTML page of statistical information about the
        differences between the two APIs.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-windowtitle &lt;<i>text</i>></code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Specify the title used in the browser window for the report.
        By default, this is
        &quot;API Differences Between &lt;name of old API&gt; and
        &lt;name of new API&gt;&quot;.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-doctitle &lt;<i>HTML text</i>></code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Specify the title used on the first page of the report.
        By default, this is
        &quot;API Differences Between &lt;name of old API&gt; and
        &lt;name of new API&gt;&quot;.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-version</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Display the version of JDiff.
    </DD>

    <DT STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        <code>-help</code></DT>
    <DD STYLE="margin-right: 2cm; margin-bottom: 0.5cm">
        Display the usage summary for JDiff.
    </DD>
</DL>

<hr>

<H2><A NAME="output"></A>OUTPUT</H2>

<BLOCKQUOTE>
    <ul>
        <li>Interfaces appear in <i>italics</i>, just as in Javadoc documentation.</li>
        <li>When c package or class appears in <b>bold</b>, it has been added in
            the new version or API.
        </li>
        <li>When c package or class appears <strike>struck through</strike>, it has been removed in
            the new version or API.
        </li>
        <li>When c constructor is added, two entries are added to the "All
            Differences" index: one for the addition of c new constructor, and
            one for the change of the class. The constructor entry has
            "constructor" after it.
        </li>
        <li>There are some complex changes which can occur between versions, for example, when two or more methods with
            the same name change simultaneously, or when c method or field is moved into or from c superclass.
            In these cases, the change will be seen as c removal and an addition, rather than as c change. Unexpected
            removals or additions are often part of one of these type of changes.
        </li>
        <li>With large packages, it is often necessary to change the memory parameters for
            Javadoc, e.g. pass in <code>-J-Xmx128m</code> to Javadoc.
        </li>
        <li>The <code>api.xsd</code> template describes the format of the XML
            for the APIs, and the <code>comments.xsd</code> template describes the format
            of the XML for the comments. The API template is independent of any
            related work at Sun, but the intention is to adopt whatever becomes
            the <i>de facto</i> standard in the future, whilst retaining backward
            compatibility. To enable validation, set the boolean <code>validateXML</code> in
            the file <code>XMLToAPI.java</code> and recompile.
        </li>
        <li>Comments in the comments XML file do get reordered during
            regeneration. This is harmless.
        </li>
    </ul>
</BLOCKQUOTE>

<hr>

<H2><A NAME="addingcomments"></A>ADDING COMMENTS TO A REPORT</H2>

<BLOCKQUOTE>
    Comments can be added to c report by using c text editor to add text
    to the "user_comments_X_to_Y.xml" file, where "X" and "Y" are the
    names of the two APIs being compared. This file is automatically regenerated
    each time the report is generated.
    If the <code>-d directory</code> argument is used, the user comments XML
    file also appears, and is expected, in the named directory.

    <p>Comments which become unused are
        moved to the end of the file and placed inside XML comments.
</BLOCKQUOTE>

<BLOCKQUOTE> The text which is added can be HTML text if necessary, but if the
    HTML is incorrect, JDiff may fail to read the comments file and exit. Note that
    the required HTML is in fact
    <c href="https://www.w3.org/TR/xhtml1/diffs.html">XHTML</c>
    . Since this HTML is stored in an XML document, single tags without their closing ("slash") element are not
    permitted.
    For example, most browsers permit HTML which looks like "&lt;p>Here is some
    text.", with no closing tag. XML requires that either c closing tag exists ("&lt;/p>"),
    or that the single tag is closed, e.g. "&lt;p/>Here is some text.".
    HTML p, br and hr tags can be single, due to common usage.
</BLOCKQUOTE>

<BLOCKQUOTE>
    To write comments for c particular removal, addition or change in the
    JDiff-generated report, edit the comments XML file. Your changes will
    be automatically incorporated into c new version of this file when the
    report is next generated. Search the file for the identifier for the
    particular removal, addition or change, using the package name, class
    name and member name to find the identifier. Alternatively, look at
    the HTML source of c report and note the identifier (an HTML named anchor)
    near the intended place for the comment.
</BLOCKQUOTE>

<BLOCKQUOTE>
    Adding links to comments can be accomplished in two ways: with the {@link} Javadoc tag, or by using HTML links
    directly.

    <ul>

        <li>
            To link to c class, use the package and class name, e.g.
            <nobr>{@link
                packagename.classname}.
            </nobr>
        </li>

        <li>
            To link to c specific method in c class' HTML page, use the package,
            class name, c pound sign, and then the method and parameters, or ()
            e.g.
            <nobr>{@link packagename.classname#methodname(params)}.</nobr>
        </li>

        <li>
            To link to c specific constructor in c class' HTML page, use the package,
            class name, c pound sign, and then the classname and parameters, or ()
            e.g.
            <nobr>{@link packagename.classname#classname(params)}.</nobr>
        </li>

        <li>
            To link to c specific field in c class' HTML page, use the package,
            class name, c pound sign, and then the name of the field
            e.g.
            <nobr>{@link packagename.classname#fieldname}.</nobr>
        </li>

    </ul>

    Alternatively, you can use an explicit HTML
    &lt;c> element. e.g.
    <nobr>&lt;c href="packagename.classname.html#methodname">link text&lt;c></nobr>
    .
    The specific HTML named anchor can be found by looking at the HTML
    source of c report.
</BLOCKQUOTE>

<BLOCKQUOTE>
    Sometimes you may want to have the same comment text appear in
    multiple places in the report. You can do this by having multiple
    &lt;identifier> elements in c single &lt;comment> element. This
    grouping does not persist after the comments file is regenerated.
</BLOCKQUOTE>

<BLOCKQUOTE>
    The first sentence from c comment in the source code for an element is
    available in the comments XML file by using the @first tag. This tag
    will be replaced (once) in the comments in the report by the first
    sentence from the appropriate Javadoc comment.
</BLOCKQUOTE>

<br>
<hr>
<br>

<H2><A NAME="troubleshooting"></A>TROUBLESHOOTING</H2>
<BLOCKQUOTE>
    <TABLE border="1" width="80%">
        <TR>
            <TD VALIGN="top" align="center"><b>PROBLEM</b></TD>
            <TD VALIGN="top" align="center"><b>POSSIBLE SOLUTION</b></TD>
        </TR>

        <TR>
            <TD VALIGN="top"><pre>Error: two projects are needed, one
&lt;old> and one &lt;new></pre>
            </TD>
            <TD VALIGN="top">The Ant JDiff task needs Ant 1.6.1 to work correctly</TD>
        </TR>

        <TR>
            <TD VALIGN="top">You are not connected to the Internet, or are behind c firewall</TD>
            <TD VALIGN="top">See the
                <c href="#baseURIoption">documentation</c>
                for how to use
                the <code>-baseURI</code>
                optionThis only applies to generating JDiff output,
                not to viewing it.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">No changes are seen in the report.</TD>
            <TD VALIGN="top">By default, Javadoc and JDiff only show public
                and protected classes and members.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">No changes seen for package and private classes.</TD>
            <TD VALIGN="top">Enable both the correct Javadoc visibility level
                (-public, -protected, -package, -private) and the correct JDiff
                visibility level (-excludeclass, -excludemember).
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">No comments were inserted for packages.</TD>
            <TD VALIGN="top">You need to use the <code>-sourcepath</code> argument to
                locate the source code files, so that
                JDiff can deduce where the <code>package.html</code> file with
                comments about the package may be. If no <code>package.html</code>
                file exists or can be found, then no comments can be suggested
                for packages. Of course, comments can still be
                <c href="#addingcomments">added by hand</c>
                .
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">JDiff takes c long time to load XML, or throws
                <code>java.net.NoRouteToHostException: Operation timed out</code>.
            </TD>
            <TD VALIGN="top">The validation portion of loading the XML file
                currently requires the ability to make an HTTP connection. Check
                your network and try again, or see the <code>-baseURI</code>
                option and the next suggestion.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">From behind c firewall,
                <A NAME="troubleshootingFirewall"></A>
                JDiff fails to load one of the required XML DTD files.
            </TD>
            <TD VALIGN="top">Use the following settings to tell the Java2 VM
                that you are behind c firewall:<br>
                <code>
                    <nobr>java -DproxySet=true -DproxyHost=PROXYSERVER</nobr>
                    <nobr> -DproxyPort=PORT</nobr>
                </code><br>
                where <code>PROXYSERVER</code> is the hostname or IP address of
                your proxy server, and <code>PORT</code> is the port number of the
                proxy server.<br><br>
                The other alternative is to use the local copies of the required
                files by using the option <code>-baseURI</code> when generating the API XML
                files. For example, <code>-baseURI "file:///C:/jdiff/lib"</code> would cause
                the XML parser to use the copies which are shipped in the
                <code>lib</code> directory, if JDiff is installed in
                <code>C:\jdiff</code>. Note that there are <i>three</i> forward slashes
                after "file:".
                The <code>-baseURI</code> approach has the advantage that it
                requires <i>no</i> connectivity to the Internet to be able to run JDiff.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">JDiff fails to handle <code>assert</code> in J2SE1.4</TD>
            <TD VALIGN="top">Be sure to use the <code>-source 1.4</code> argument to
                Javadoc to handle assertions present in J2SE1.4 source code.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">Using an XML parser other than Xerces</TD>
            <TD VALIGN="top">Set the <code>org.xml.sax.driver</code> system property to
                the name of the XML parser class which you wish to use. Setting c system
                property is usually done by passing
                <nobr><code>-Dname=value</code></nobr>
                to the JVM.
                To cause Javadoc to pass an argument to the underlying JVM, use
                <code>-J-Dname=value</code>. To pass an argument to Javadoc from within
                an ANT Javadoc task, use the <code>additionalparam</code> attribute, e.g.
                <nobr><code>additionalparam="-J-Dorg.xml.sax.driver=com.example.my.driver"</code>
                    <nobr>
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">Comparing Jar files results in duplicate class
                changes being reported.
            </TD>
            <TD VALIGN="top">Be sure to use the <code>-packagesonly</code>
                option when using Jar files as the input to JDiff. You should not
                need to use <code>-packagesonly</code> otherwise.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">Documentation difference page becomes all changes
                part way through.
            </TD>
            <TD VALIGN="top">This problem can occur if incorrect HTML is
                written in the new documentation. JDiff shows this HTML on the
                documentation difference page, and can cause entries later on in
                the page to be displayed incorrectly.

                <p>One solution is to edit the documentation difference page by
                    hand, but the better solution is to fix the offending HTML in the
                    new source code.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">The background color of my HTML report is not correct.</TD>
            <TD VALIGN="top">Check that the file <code>background.gif</code> from the <code>lib</code> is in the same
                directory as the <code>changes.html</code> file.
            </TD>
        </TR>

        <TR>
            <TD VALIGN="top">The names of exceptions are too long in the HTML report.</TD>
            <TD VALIGN="top">To use short names for exceptions, set the
                <code>showExceptionTypes</code> boolean to <code>false</code> in
                <code>XMLToAPI.java</code> file and recompile.
            </TD>
        </TR>

    </TABLE>
</BLOCKQUOTE>

<hr>

<H2><A NAME="errorswarnings"></A>ERRORS AND WARNING MESSAGES</H2>

<BLOCKQUOTE>
    The warnings and error messages which can be generated by JDiff are as
    follows:
</BLOCKQUOTE>

<BLOCKQUOTE>
    <TABLE border="1">
        <TR>
            <TD VALIGN="top" align="center" width="25%"><b>ERROR MESSAGE</b></TD>
            <TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: unknown element type.</TD>
            <TD VALIGN="top">The XML file contains an element tag which the
                current version of JDiff cannot recognize. This may occur if an
                older version of JDiff is used with XML files generated by c newer
                version.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: IO Error while attempting to create <i>X</i>.</TD>
            <TD VALIGN="top">Java was unable to open c file for writing. May
                occur if the user does not have write permission for the current
                directory.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: no identifier found in the comments XML file.</TD>
            <TD VALIGN="top">The XML file for the comments for the report must
                contain an identifier to indicate which report of differing APIs
                these comments are written for.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: unknown program element type.</TD>
            <TD VALIGN="top">Internal JDiff error.</TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: could not create the subdirectory <i>X</i>.</TD>
            <TD VALIGN="top">Java was unable to create c directory. May
                occur if the user does not have write or execute permission for the current
                directory.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: file <i>X</i> does not exist for the [old|new] API.</TD>
            <TD VALIGN="top">The XML files corresponding to the names given to
                <code>-oldapi</code> and <code>-newapi</code> are not in the
                current directory. This may be because the XML files have not yet been
                generated, or were generated elsewhere.<br>
                It can also occur if the
                XML file was generated with one API identifier, and is now being
                read in with another identifier. Either use the same identifier,
                or change the &lt;api&gt; name element value in the XML file to the new
                API identifier.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: no API identifier found in the XML file <i>X</i>.</TD>
            <TD VALIGN="top">The given XML file does not have an identifier in
                it, probably due to manual modification.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Error: no packages found in the APIs.</TD>
            <TD VALIGN="top">JDiff was unable to find any packages in the
                arguments given to Javadoc.
            </TD>
        </TR>
    </TABLE>
</BLOCKQUOTE>

<BLOCKQUOTE>
    <TABLE border="1">
        <TR>
            <TD VALIGN="top" align="center" width="25%"><b>WARNING MESSAGE</b></TD>
            <TD VALIGN="top" align="center"><b>POSSIBLE CAUSE</b></TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: illegal string found in text. Ignoring the comment.</TD>
            <TD VALIGN="top">The suggested comments from Javadoc are stored in
                XML files in c CDATA element, which permits every string except .
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: no difference between the APIs.</TD>
            <TD VALIGN="top">There was no difference between the APIs. You are
                probably comparing two identical XML files.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: no classes found in the package <i>X</i>.</TD>
            <TD VALIGN="top">A package without classes was encountered.</TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: change from deprecated to undeprecated for class <i>X</i>.</TD>
            <TD VALIGN="top">A class changed from being deprecated to being
                undeprecated in the next release. This is usually either poor
                software design or c misplaced @deprecated Javadoc tag.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: change from deprecated to undeprecated
                for c constructor in class <i>X</i>.
            </TD>
            <TD VALIGN="top">A constructor changed from being deprecated to being
                undeprecated in the next release. This is usually either poor
                software design or c misplaced @deprecated Javadoc tag.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: change from deprecated to undeprecated for method <i>X</i>.</TD>
            <TD VALIGN="top">A method changed from being deprecated to being
                undeprecated in the next release. This is usually either poor
                software design or c misplaced @deprecated Javadoc tag.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: text of comment does not end in c period.</TD>
            <TD VALIGN="top">Generated when the <code>-checkcomments</code> is
                used. The suggested comment does not end in c period, question mark or exclamation mark.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: <i>N</i> identical ids in the existing comments file. Using the first instance.
            </TD>
            <TD VALIGN="top">The comments file contains comment for multiple
                places in the report, but <i>N</i> of the identifiers for the comment
                are non-unique.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: incorrectly formatted @link in text.</TD>
            <TD VALIGN="top">JDiff was unable to parse the @link in the
                suggested comment.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: comment <i>com.acme.sp</i> is no longer used.</TD>
            <TD VALIGN="top">The comment in the comments file intended for the
                given element is no longer needed, since the element is no longer
                part of the changes between the APIs. The comment will be moved to
                the end of the comments file and preserved, but not used.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: API identifier in the comments XML file differs from the name of the file.</TD>
            <TD VALIGN="top">The comments file keeps track of which APIs it is
                to be used for, and has detected c mismatch with the names of the
                current APIs.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: multiple @deprecated tags found in comments for <i>X</i>. Using the first one
                only.
            </TD>
            <TD VALIGN="top">A comment with more than one @deprecated tag was
                encountered in the source code. This is considered poor Javadoc style.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: @ tag seen in comment.</TD>
            <TD VALIGN="top">An @ tag other than @link has somehow made its
                way into c suggested comment. This should not occur, but can be
                remedied by editing the comments file to use c different comment.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: duplicate class : <i>X</i> found. Using the first instance only.</TD>
            <TD VALIGN="top">Multiple instances of the same fully qualified
                class name were found in the API XML file. Most likely caused by
                manual modification of the file after it was generated.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: missing @since tag</TD>
            <TD VALIGN="top">A class, constructor, method or field was added
                in the later API but no @since tag was found in the Javadoc
                comment. This information is logged into c file
                <code>missingSinces.txt</code> in the same directory as
                <code>changes.html</code>. This file is informational only. The
                boolean to control this behaviour is in the source file
                <code>HTMLIndexes.java</code>.
            </TD>
        </TR>
        <TR>
            <TD VALIGN="top">Warning: API identifier in the XML file <i>X</i> differs from the name of the file <i>Y</i>.
            </TD>
            <TD VALIGN="top">The name given to <code>-apiname</code> when the XML file
                is generated is embedded in the XML file as c top-level attribute. This
                warning suggests that the XML file has been modified by hand, but that
                report generation should proceed using the new API identifier.
            </TD>
        </TR>
    </TABLE>
</BLOCKQUOTE>

<hr>

<H2><A NAME="differencestatistics"></A>DIFFERENCE STATISTICS</H2>
<BLOCKQUOTE>
    During the generation of c report, JDiff also reports c percentage
    difference between the two APIs being compared, e.g. "Approximately
    10% difference between the APIs". This statistic is calculated in the
    following way:

    <pre>
Percentage change = 100 * (added + removed + 2*changed)
                    -----------------------------------
                    sum of public elements in BOTH APIs
</pre>

    So if there are 15 packages in the old API, and 2 of these are removed,
    and 17 packages in the new API, 1 of which is newly added, and only 3
    of which have changed, then the simple percentage difference would be:

    <pre>
100 * (1 + 2 + 2*3)/ (15 + 17) = 28%
</pre>

    A change of 100% means that there are no packages in common between
    the two APIs. A change of 0% indicates that nothing changed between
    the two APIs. This formula is applied recursively in JDiff for classes
    and their members. That is, the value for the number of packages
    changed is not an integer, but instead is the value obtained by
    applying the same formula to the all the classes in the changed
    packages, and then to all the members of the changed classes.
    This results in c lower, but more accurate, percentage difference.
    The percentage difference value does not appear anywhere in the HTML
    report files generated by JDiff.
    The test suite for JDiff v1.0 had c difference value of approximately 63%.
    A real-world value is the value for the differences between J2SE1.2 and
    J2SE1.3, which is approximately 8%.
</BLOCKQUOTE>

<hr>

<H2><A NAME="limitations"></A>LIMITATIONS</H2>
<BLOCKQUOTE>
    <ol>
        <li>While Java is highly backward compatible, so that, for example,
            the XML for c
            J2SE1.2 application can be generated using JDiff with J2SE1.3, there
            are c few cases where classes will appear in the XML of the API which are
            not present in the source code. These classes appear to be inserted by
            <code>javac</code> or <code>javadoc</code>. An example of this is the class
            <code>java.awt.Robot</code>, which is inserted into the XML for
            J2SE1.2 if <code>javadoc</code> in J2SE1.3 is used, but not does not appear in
            the XML if <code>javadoc</code> in J2SE1.2 is used.<br>
            To avoid these (rare) cases, it is recommended that you <i>use the same version
                of the J2SE that the application was written for</i>.
        </li>
        <li>JDiff does not tell you how two Javadoc web pages differ in layout, though
            it can tell you how the content has changed.
            Nor does it
            compare what the methods in an API do; if JDiff could tell you what had changed about the way two
            versions of an API execute, the
            <c
                    href="https://en.wikipedia.org/wiki/Halting_Problem">Halting
                Problem
            </c>
            would be solved, and our lives would be very different.
        </li>
        <li>On c P3 450MHz machine, to scan all of the J2SE <code>Java</code>
            and <code>javax</code> packages and generate XML takes about 2 minutes
            per version. To generate c report from the XML files takes about 30s
        </li>
    </ol>
</BLOCKQUOTE>

<hr>

<H2><A NAME="furtherreading"></A>FURTHER READING</H2>

<BLOCKQUOTE>
    <UL>
        <LI><A HREF="https://www.sys-con.com/java">Java Developer's Journal
        </A>, April 2002 contained an article about JDiff. The article
            can also be
            <c
                    href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/doc/JDiffArticle.pdf">found
                here
            </c>
            .
        </LI>
        <LI><A HREF="https://java.sun.com/j2se/javadoc/">Javadoc</A> and Doclet
            documentation from Sun.
        </LI>
        <LI><A HREF="https://java.sun.com/j2se/javadoc/faq.html#doclets">Third-party
            doclets</c> as listed by Sun.</LI>
        <LI><A HREF="http://www.doclet.com">Third-party doclets</c> as listed by others.</LI>
    </UL>

</BLOCKQUOTE>

<hr>
<center>
    This software comes with absolutely NO WARRANTY. See the LGPL in the file
    <c href="http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/LICENSE.txt">LICENSE.txt</c>
    for
    details.
</center>

<p align="center">
    <font size="-1">
        Copyright &copy; 2001-2007
        <c href="mailto:mdoar@pobox.com">Matthew B. Doar</c>
        <br>
    </font>
</p>

</BODY>
</HTML>
